// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_PARSER_CPDF_INDIRECT_OBJECT_HOLDER_H_
#define CORE_FPDFAPI_PARSER_CPDF_INDIRECT_OBJECT_HOLDER_H_

#include <stdint.h>

#include <map>
#include <type_traits>
#include <utility>

#include "core/fpdfapi/parser/cpdf_object.h"
#include "core/fxcrt/retain_ptr.h"
#include "core/fxcrt/string_pool_template.h"
#include "core/fxcrt/weak_ptr.h"

class CPDF_IndirectObjectHolder {
 public:
  using const_iterator =
      std::map<uint32_t, RetainPtr<CPDF_Object>>::const_iterator;

  CPDF_IndirectObjectHolder();
  virtual ~CPDF_IndirectObjectHolder();

  RetainPtr<CPDF_Object> GetOrParseIndirectObject(uint32_t objnum);
  RetainPtr<const CPDF_Object> GetIndirectObject(uint32_t objnum) const;
  RetainPtr<CPDF_Object> GetMutableIndirectObject(uint32_t objnum);
  void DeleteIndirectObject(uint32_t objnum);

  // Creates and adds a new object retained by the indirect object holder,
  // and returns a retained pointer to it.
  template <typename T, typename... Args>
  RetainPtr<T> NewIndirect(Args&&... args) {
    auto obj = New<T>(std::forward<Args>(args)...);
    AddIndirectObject(obj);
    return obj;
  }

  // Creates and adds a new object not retained by the indirect object holder,
  // but which can intern strings from it. We have a special cast to handle
  // objects that can intern strings from our ByteStringPool.
  template <typename T, typename... Args>
  typename std::enable_if<CanInternStrings<T>::value, RetainPtr<T>>::type New(
      Args&&... args) {
    return pdfium::MakeRetain<T>(m_pByteStringPool,
                                 std::forward<Args>(args)...);
  }
  template <typename T, typename... Args>
  typename std::enable_if<!CanInternStrings<T>::value, RetainPtr<T>>::type New(
      Args&&... args) {
    return pdfium::MakeRetain<T>(std::forward<Args>(args)...);
  }

  // Always Retains |pObj|, returns its new object number.
  uint32_t AddIndirectObject(RetainPtr<CPDF_Object> pObj);

  // If higher generation number, retains |pObj| and returns true.
  bool ReplaceIndirectObjectIfHigherGeneration(uint32_t objnum,
                                               RetainPtr<CPDF_Object> pObj);

  uint32_t GetLastObjNum() const { return m_LastObjNum; }
  void SetLastObjNum(uint32_t objnum) { m_LastObjNum = objnum; }

  WeakPtr<ByteStringPool> GetByteStringPool() const {
    return m_pByteStringPool;
  }

  const_iterator begin() const { return m_IndirectObjs.begin(); }
  const_iterator end() const { return m_IndirectObjs.end(); }

 protected:
  virtual RetainPtr<CPDF_Object> ParseIndirectObject(uint32_t objnum);

 private:
  friend class CPDF_Reference;

  const CPDF_Object* GetIndirectObjectInternal(uint32_t objnum) const;
  CPDF_Object* GetOrParseIndirectObjectInternal(uint32_t objnum);

  uint32_t m_LastObjNum = 0;
  std::map<uint32_t, RetainPtr<CPDF_Object>> m_IndirectObjs;
  WeakPtr<ByteStringPool> m_pByteStringPool;
};

#endif  // CORE_FPDFAPI_PARSER_CPDF_INDIRECT_OBJECT_HOLDER_H_
`CPDF_IndirectObjectHolder` 类提供了管理 PDF 间接对象的功能，该类允许创建、检索、替换和删除间接对象。以下是该接口的功能列表：

### CPDF_IndirectObjectHolder 类

#### 公共方法
1. * *CPDF_IndirectObjectHolder() * *: 构造函数，初始化对象持有器。
2. * *virtual ~CPDF_IndirectObjectHolder() * *: 虚析构函数，销毁对象持有器。
3. * *RetainPtr<CPDF_Object> GetOrParseIndirectObject(uint32_t objnum) * *: 获取或解析指定的间接对象。
4. * *RetainPtr<const CPDF_Object> GetIndirectObject(uint32_t objnum) const** : 获取指定的间接对象（只读）。
5. * *RetainPtr<CPDF_Object> GetMutableIndirectObject(uint32_t objnum) * *: 获取指定的间接对象（可修改）。
6. * *void DeleteIndirectObject(uint32_t objnum) * *: 删除指定的间接对象。
7. * *template <typename T, typename... Args> RetainPtr<T> NewIndirect(Args&&... args) * *: 创建并新增一个被间接对象持有器管理的新对象，并返回一个保留指针。
8. * *template <typename T, typename... Args> RetainPtr<T> New(Args&&... args) * *: 创建并新增一个未被间接对象持有器管理的对象，并支持从 `ByteStringPool` 内部化的字符串。
9. * *uint32_t AddIndirectObject(RetainPtr<CPDF_Object> pObj) * *: 新增一个间接对象并返回其对象编号。
10. * *bool ReplaceIndirectObjectIfHigherGeneration(uint32_t objnum, RetainPtr<CPDF_Object> pObj) * *: 如果版本号较高，则替换间接对象。
11. * *uint32_t GetLastObjNum() const** : 获取最后一个对象编号。
12. * *void SetLastObjNum(uint32_t objnum) * *: 设置最后一个对象编号。
13. * *WeakPtr<ByteStringPool> GetByteStringPool() const** : 获取 `ByteStringPool`，用于管理字符串内存。
14. * *const_iterator begin() const** : 获取间接对象集合的起始迭代器。
15. * *const_iterator end() const** : 获取间接对象集合的结束迭代器。

#### 保护方法
16. * *virtual RetainPtr<CPDF_Object> ParseIndirectObject(uint32_t objnum) * *: 解析指定的间接对象。

#### 私有方法
17. * *const CPDF_Object * GetIndirectObjectInternal(uint32_t objnum) const** : 内部方法，获取指定的间接对象（只读）。
18. * *CPDF_Object * GetOrParseIndirectObjectInternal(uint32_t objnum) * *: 内部方法，获取或解析指定的间接对象。

这些方法总的来说负责在 PDF 文件处理中对特殊对象的管理，特别是需要解析、创建或操纵 PDF 间接对象时，经常会用到这些接口。